nLIGHTn beta2
by Necroman

(where "beta" stands for "beta than nothing" :-)

Introduction

nLIGHTn (read as "enlighten") provides access to a subset of OpenGL 1.1. OpenGL is used by plenty of "serious" applications and games to produce still and animated 3D graphics (the most popular example would be Quake III).

Your job as an OpenGL programmer is to specify the 3D coordinates of your objects and light sources. You tell the system what rotations it should perform, what textures it should map, and OpenGL builds the picture accordingly.

Beta2 does not cover all OpenGL 1.1 functionality. Advanced things (maps, meshes, splines, evaluators, color indices, vertex arrays, stencil buffer, and the like) are not yet implemented. Still, you have more than 100 functions to play with.

The proper way to learn nLIGHTn is to learn OpenGL first . This help file is not newbie-friendly, it is NOT an OpenGL tutorial (just like mirc.hlp does not explain regular expressions or COM objects). It focuses on nLIGHTn specifics only.

The References section below contains links to some OpenGL resources. Don't be confused by the fact that OpenGL was designed for C programmers - you don't have to know C to understand what glEnable(GL_LIGHTING) means.

Don't be afraid to ask nLIGHTn-related questions by e-mail or via IRC. Your questions can help this help file grow into real documentation.

Syntax

nLIGHTn provides its functionality through a single function named gl. For example:

//dll nLIGHTn gl begin polygon

//echo -a $dll(nLIGHTn,gl,version)

All the names of nLIGHTn functions and constants usually resemble their OpenGL equivalents and are case- and underscore-insensitive. For example, the OpenGL function glGetLightfv is accessible as GetLight, or get_light.

Devices

The first thing you should do is to obtain the handle of the window you want to render graphics on. This is how it is done for a custom @window:

//dll nLIGHTn gl attach $window(@test).hwnd

Any HWND will work. You can attach devices to dialog controls, for instance.

Once a rendering device is attached to a window, it is selected to be the current one. If the window already has a device attached, attach simply selects it. There can be several add-ons using nLIGHTn, so always call attach when you start your scene, otherwise you may end up drawing on a wrong window.

On attaching a device you can "import" display lists and fonts from another device. To do that, specify its HWND in the second parameter:

//dll nLIGHTn gl attach $window(@test).hwnd $window(@import).hwnd

You can't do that with textures. You must reload them.

Input Arguments

nLIGHTn tries to interpret input arguments as floating point numbers. If a token starts from a non-numeric symbol, nLIGHTn attempts to view it as an OpenGL constant (to make it possible for you to write enable lighting instead of enable 2896).

To add several constants together, concatenate them using the ampersand:

//dll nLIGHTn gl push_attrib TRANSFORM_BIT & ENABLE_BIT

When an OpenGL function can return a variable number of values, its lazy nLIGHTn equivalent requires an extra parameter: the number of values you expect. For example, to get the current projection matrix in C++ you write something like this:

float matrix[16]; glGetFloatv(GL_PROJECTION_MATRIX,matrix);

With nLIGHTn, you will use

//echo -a $dll(nLIGHTn,gl,GetFloat PROJECTION_MATRIX 16)

Sometimes, nLIGHTn allows you to omit certain arguments. Most of such simplifications are undocumented - you can safely ignore them and script in "pure OpenGL".

Return Values

nLIGHTn passes input arguments to OpenGL without any error checking. For example, if you type

//echo -a $dll(nLIGHTn,gl,disable terrorists)

the return value will be S_OK. You can retrieve the last OpenGL error code:

//echo -a $dll(nLIGHTn,gl,get_error)

Specific nLIGHTn functions do return error messages, like E_INVALID_WINDOW or E_FAILED.

Double Buffering

nLIGHTn enforces double-buffering. That is, you draw on the hidden surface and call swap_buffers to bring it to the foreground. To display animation, you create a high-resolution (-h) or multimedia (-m) timer and render frames quickly, one by one.

Scaling Modes

nLIGHTn has 3 scaling modes, which can be set using the auto_scale function:

//dll n nLIGHTn gl auto_scale 2 45 1 100

Here 2 is the mode number, 45 is the view angle, 1 is the distance from the camera to the near clipping plane, 100 is the distance from the camera to the far clipping plane.

Mode 1 is default. In this mode nLIGHTn automatically resizes the image while keeping its original proportions.

Mode 2 does not attempt to keep image proportions.

Mode 0 is special. In this mode, nLIGHTn does not attempt to resize the image at all. Instead, upon returning from the attach function, if the host window has been resized, nLIGHTn executes /signal -n nLIGHTn hwnd SIZE width height. , allowing you to perform custom resizing (usually with viewport and perspective ).

Fonts

The bind_font function selects fonts. Think up a unique number and pass it to bind_font as the font ID.

The left, right, top and bottom specifiers describe horizontal and vertical text alignment (text is centered vertically and horizontally by default). Example:

//dll nLIGHTn gl bind_font 2 right top

After initial bind_font, call create_font to generate a display list for 256 characters. After that, you can use print, text_width and text_height . Switch between fonts with bind_font.

Example:

//dll nLIGHTn gl create_font Times_New_Roman 400 RUSSIAN 0.1 0.005 1 1 1

The first token is the font name (replace spaces with underscores).

The second number is the font weight. 400 is normal, 800 is bold.

The third constant is the character set. Can be ANSI, BALTIC, CHINESEBIG5, DEFAULT, EASTEUROPE, GB2312, GREEK, HANGUL, MAC, OEM, RUSSIAN, SHIFTJIS, SYMBOL, or TURKISH.

The fourth number is the thickness of the font. The fifth is the deviation of the font (the smaller it is, the smoother the characters are and the slower the rendering is). The next three booleans are italic, strikeout and underline flags.

The print function draws text in the X0Y plane. You need to apply 3D transformations to position the text where you want to see it.

The text_width and text_height functions return the total width of a string and its maximum height, respectively.

Textures

The bind_texture function selects textures. You should supply a unique texture ID (texture IDs do not conflict with those of fonts or display lists), or get one from gen_textures.

After initial bind_texture, load it from a BMP file using load_texture. You can switch between textures using bind_texture.

nLIGHTn beta2 only supports 24-bit BMP files.

Display lists

Some OpenGL calls can be "compiled" into display lists for efficiency. Display lists are stored by your graphics card driver, and executed with call_list or call_lists. They are the tool to make your mIRC animations faster.

Think up a unique list ID (or get one from gen_lists) and start a new list with the new_list command. All commands between new_list and end_list will not be executed, but compiled into the list (actually new_list also supports the compile_and_execute flag).

The following example compiles a red triangle into list 10000:

//dll nLIGHTn gl new_list 10000
//dll nLIGHTn gl color 1 0 0
//dll nLIGHTn gl begin triangles
//dll nLIGHTn gl vertex 1 0 0 | dll nLIGHTn gl vertex 0 1 0 | dll nLIGHTn gl vertex 0 0 0
//dll nLIGHTn gl end
//dll nLIGHTn gl end_list

Quadrics

nLIGHTn supports the 4 primitive 3D shapes ("quadrics") from the OpenGL utility library: disk, partial disk, sphere and cylinder.

nLIGHTn also accepts 4 additional parameters which it passes to gluQuadricDrawStyle(), gluQuadricOrientation(), gluQuadricNormals(), and gluQuadricTexture(), correspondingly.

The following line generates a solid textured sphere with radius 10, consisting of 20 stacks and 20 slices, with normals pointing inward, and smooth shading:

//dll nLIGHTn gl sphere 10 20 20 glu_fill glu_inside glu_smooth true

Functions

version information

version

returns version information

device control

attach	attaches a rendering device to a window
detach	detaches the current rendering device
swap_buffers	brings the hidden frame to the foreground
accum	operates on the accumulation buffer
full_screen	not currently supported
auto_scale	sets auto-resize mode

textures

gen_textures	generates unique texture IDs
bind_texture	selects current texture
is_texture	determines if an ID corresponds to a texture
load_texture	loads a texture from a .BMP file
get_tex_level_parameter	returns texture parameters for a specific level of detail
tex_env	sets texture environment parameters
get_tex_env	returns texture environment parameters
tex_gen	controls automatic generation of texture coordinates
get_tex_gen	returns texture coordinate generation parameters
tex_parameter	sets texture parameters
get_tex_parameter	gets texture parameters
copy_tex_image	copies pixels from the frame buffer into a two-dimensional texture image
copy_tex_image_2d	same as above
copy_tex_sub_image	copies a sub-image of a two-dimensional texture image from the frame buffer
copy_tex_sub_image_2d	same as above
delete_textures	deletes textures from memory

text

bind_font	selects current font
is_font	determines if an ID corresponds to a font
create_font	creates display lists for all the characters in a font
text_width	calculates the width of a string
text_height	calculates the maximum height of a string
print	outputs text to the X0Y plane
delete_font	deletes a font

bitmap	not actually supported
raster_pos	sets the current raster position for pixel operations
copy_pixels	copes pixels in the frame buffer
draw_pixels	draws pixels in the frame buffer
rect	draws a rectangle
scissor	defines the scissor box
pixel_transfer	sets pixel transfer modes
viewport	sets the viewport coordinates
pixel_zoom	specifies the pixel zoom factors

clear

clear	clears buffers to preset values
clear_accum	clears values for the accumulation buffer
clear_color	specifies clear values for the color buffers
clear_depth	specifies the clear value for the depth buffer

vertices and coordinates

begin	starts a primitive or a group of like primitives
vertex	specifies a vertex
front_face	defines front- and back-facing polygons
normal	sets the current normal vector
tex_coord	set the current texture coordinates
edge_flag	flag edges as either boundary or non-boundary
end	ends a primitive or a group of like primitives

colors and materials

color	sets the current color
color_mask	enables and disables writing of frame-buffer color components
color_material	causes a material color to track the current color
material	specifies material parameters for the lighting model
get_material	returns material parameters
fog	specifies fog parameters

test function

blend_func	specifies pixel arithmetic
alpha_func	specifies the alpha test function
depth_func	specifies the value used for depth-buffer comparisons

display lists

new_list	creates or replaces a display list
gen_lists	generates unique IDs for display lists
is_list	tests for display list existence
call_list	executes a display list
list_base	sets the display list base for call_lists
call_lists	calls a list of display lists
end_list	marks the end of a display list
delete_lists	deletes display lists

misc

disable	disable OpenGL capabilities
enable	enable OpenGL capabilities
is_enabled	tests whether a capability is enabled
cull_face	specifies whether front- or back-facing facets can be culled
depth_mask	enables or disables writing into the depth buffer
depth_range	specifies the mapping of z values from normalized device coordinates to window coordinates
light_model	set lighting model parameters
shade_model	selects flat or smooth shading
hint	specifies implementation-specific hints
polygon_mode	selects a polygon rasterization mode
polygon_offset	specifies the offset of a polygon
line_stipple	specifies the line stipple pattern
line_width	specifies the width of rasterized lines
point_size	specifies the diameter of rasterized points
push_attrib	pushes the attribute stack
pop_attrib	pops the attribute stack

accessors

get_boolean	return the value or values of a selected parameter as $true or $false
get_double	return the value or values of a selected parameter as double-precision floating-point numbers
get_float	return the value or values of a selected parameter as single-precision floating-point numbers
get_integer	return the value or values of a selected parameter as integers
get_string	return the value or values of a selected parameter as text
get_error	returns and clears information about the last error

light

light	sets light source parameters
get_light	returns light source parameter values

clip_plane	specifies a plane against which all geometry is clipped
get_clip_plane	returns the coefficients of the specified clipping plane
load_identity	replaces the current matrix with the identity matrix
load_matrix	replaces the current matrix with an arbitrary matrix
matrix_mode	specifies which matrix is the current matrix
mult_matrix	multiplies the current matrix by an arbitrary matrix
pop_matrix	pops the current matrix stack
push_matrix	pushes the current matrix stack
frustum	multiplies the current matrix by a perspective matrix
ortho	multiplies the current matrix by a orthographic matrix
perspective	sets up a perspective projection matrix
rotate	multiplies the current matrix by a rotation matrix
scale	multiplies the current matrix by a general scaling matrix
translate	multiplies the current matrix by a translation matrix
look_at	defines a viewing transformation

glu

project	maps object coordinates to window coordiantes
unproject	maps window coordinates to object coordinates
sphere	creates a sphere
disk	creates a disk
partial_disk	creates a partial disk
cylinder	creates a cylinder

References

The #mIRC channel at Undernet
(be wise)

http://www.opengl.org
(the official OpenGL site)

http://ask.ii.uib.no/ebt-bin/nph-dweb/dynaweb/SGI_Developer/OpenGL_PG
(the Red Book)

http://necroman.wot.net/wingl.zip
(Microsoft OpenGL reference)

http://www.gamedev.net/reference/list.asp?categoryid=31
(gamedev)

http://www.codeguru.com/opengl/index.shtml
(codeguru)

Copyright

There is none. If you think you can improve nLIGHTn, do it.

nLIGHTn beta2 by Necroman

Introduction

Syntax

nLIGHTn beta2
by Necroman